execa

What is execa?

The execa npm package is a process execution tool that simplifies working with child processes in Node.js. It provides a better user experience than the default child_process module by offering a promise-based API, improved Windows support, and additional convenience options.

What are execa's main functionalities?

Executing a shell command

This feature allows you to execute a shell command and obtain the result. The example shows how to execute the 'echo' command and print 'unicorns' to the console.

const execa = require('execa');

(async () => {
  const { stdout } = await execa('echo', ['unicorns']);
  console.log(stdout);
})();

Running a command synchronously

This feature is used to execute a command synchronously, blocking the event loop until the process has finished. The example synchronously executes the 'echo' command and logs the result.

const execa = require('execa');

const { stdout } = execa.sync('echo', ['unicorns']);
console.log(stdout);

Handling errors

This feature demonstrates error handling when a command fails to execute. The example attempts to run a non-existent command and catches the error.

const execa = require('execa');

(async () => {
  try {
    const { stdout } = await execa('wrong-command');
    console.log(stdout);
  } catch (error) {
    console.error('Error occurred:', error);
  }
})();

Streaming output

This feature allows you to stream the output of a command directly to the console or another stream. The example streams the output of the 'echo' command to the process's stdout.

const execa = require('execa');

const subprocess = execa('echo', ['unicorns']);
subprocess.stdout.pipe(process.stdout);

Other packages similar to execa

shelljs

ShellJS is a portable Unix shell commands implementation for Node.js. It offers a higher-level API for executing commands but does not support returning promises natively.

cross-spawn

Cross-spawn is a cross-platform solution for spawning child processes. It aims to solve compatibility issues on Windows but does not provide a promise-based API.

README

execa

A better child_process.{execFile,exec}

Why

• Promise interface.
• Strips EOF from the output so you don't have to stdout.trim().
• Supports shebang binaries cross-platform.
• Improved Windows support.
• Higher max buffer. 10 MB instead of 200 KB.

Install

$ npm install --save execa

Usage

const execa = require('execa');

execa('echo', ['unicorns']).then(result => {
	console.log(result.stdout);
	//=> 'unicorns'
});

execa.shell('echo unicorns').then(result => {
	console.log(result.stdout);
	//=> 'unicorns'
});

API

execa(file, [arguments], [options])

Execute a file directly.

Same options as child_process.execFile.

Returns a promise for a result object with stdout and stderr properties.

execa.shell(command, [options])

Execute a command through the system shell. Prefer execa() whenever possible, as it's both faster and safer.

Same options as child_process.exec.

Returns a promise for a result object with stdout and stderr properties.

options

Additional exposed options:

stripEof

Type: boolean
Default: true

Strip EOF (last newline) from the output.

License

MIT © Sindre Sorhus